BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rbbsdocs.zip / RBBSDOCS.78 < prev next >

Wrap

Text File | 1990-11-09 | 30KB | 717 lines

7.8 RBBS-PC's "Macro" Command Support ------------------------------------- RBBS-PC's "macro" support expands a single keystroke into multiple keystrokes. It allows RBBS-PC to be tailored in even a greater variety of ways than before because a single command can be set up to invoke a sequence of multiple RBBS-PC commands. The concept is similar to the keyboard macro function found in many terminal emulators, except that in RBBS-PC the SysOp defines the macros and the caller invokes them transparently without knowing. Macros add a new dimension to RBBS-PC commands -- commands can be a full word rather than just a single letter. A macro is invoked by a name up to 8 characters. For example, "DOOR" and "OPEN" can be used to invoke doors. This makes it easy to make all commands available on a single level, since D could trigger a download, while the word DOOR will trigger the door function. Macros can be used to abbreviate a longer series of commands. If the SysOp wants to use "A)bandon conference", all that need be done is to add a macro called "A" whose content is "J M" (join main). Or if N)etmail is to be used to read Fido-net compatible message bases, a macro called "N" could be set up as "D NETMAIL" (use door called NETMAIL). RBBS-PC thus can have UNLIMITED commands. A string of RBBS-PC commands can be stored in a macro for many different types of purposes, including (but not limited to): PLANNING YOUR USER INTERFACE 7-11 setting up demos, showing a user what to do rather than just explaining it in words, automated testing of RBBS-PC features Macros can also be used to make the same type of function do different work. For example, the B)ulletin command basically displays a text file. Suppose an association wants to let persons order pamphlets and preview them on-line. Rather than bury the ordering function insider A)nswer questionnaire and the preview function inside B)ulletins, the commands PREVIEW and ORDER can be added as macros, where ORDER stands for "A ORDWHAT" AND "ORDWHAT" is a submenu listing what can be ordered. Each option on the submenu is a questionnaire. PREVIEW similarly is "B PREWHAT" where "PREWHAT" is a submenu listing the available pamphlets that are stored as text files. Macros can be built to provide interactive help to callers. For example, you can put up a macro called EZDOWN to help people download. It explains everything, asks for the file name and protocol, and tells the caller what they should be doing on their end, and then drives the download. Macros can be used to provide integrated data bases. Unlike questionnaires, you can totally control how data is written to a file. You can put in labels, or data only, put the values in quotes, separate the values by commas, etc. This is done by creating a template into which data values are written. Macros can be used to give "tours" of your RBBS-PC -- to showcase new or special features. Macros can be controlled via security level access, just like regular commands, and they can be forced to operate only in certain contexts. Macros can be - invoked anywhere within RBBS-PC -- including questionnaires, - unlimited in length, - used even when the caller has "turbo" key feature enabled, - used with SmartText (see section 7.9), - used to store responses that can be manipulated later, and - used to support graphics versions of text. It is important to remember that a macro will be ignored if its name is the same as any command. To replace a command with a macro, you must insure that the letter for the command has been reassigned. CONFIG parameters 30-34 allow such reassignments to be easily accomplished. Some contexts will not accept macros, such as when RBBS-PC prompts for a search string. Macro commands with more than one letter override all others. This means that the macro interpretation will prevail if more than one interpretation is possible. For example, in the absence of macros the command "door" would the interpreted as the command "d", so that saying "door" in the files section would be download. But a "DOOR.MCR" would be executed instead when it exists. One letter commands, however, will be executed when they match a command letter, and so any macros will be ignored that have the same one letter name the same as a command. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-12 7.8.1 How to Set Up "Macros" ---------------------------- To use macros, two CONFIG parameters must be specified: the drive/path where macro files are stored (CONFIG parameter 79) and the extension the macro files will have (CONFIG parameter 80). The defaults are "C:" and "MCR". To create a macro named X, simply create a file with prefix X and the macro extension and place in it the macro drive/path. If you are not using any macros, RBBS-PC will run faster if you specify NO macro extension in CONFIG parameter 80. The first line within a "macro" controls access to the macro, both by security level, and a limitation on the scope of the macro, in which it will be operative, including - anywhere inside a section - anywhere inside a command - only at a section and not inside. The format of the first line is: <SecLevel>/<constraint> where <SecLevel> is the minimum security required to run the macro, and <constraint> is the section (M for main, F for file, U for utility, or @ for library) and command letter the macro is confined to (use original command letter, not the reassigned ones). For example 4/M means that security level 4 is required, and the macro runs only at or inside the main section prompt. 5/MB means that security level 5 is required and the macro runs only at or inside the main section bulletin command. Thus the macro file 1.mcr 2/MJ {EN RBBS means that when inside the main J)oin, the text "RBBS" will be substituted for "1". (So "J 1" does the work of "J RBBS".) The "{EN" means not to echo what the macro substitutes (user does not see "RBBS"). To make a macro operative only at a section prompt and not inside, add a " /" to the end of the section constraint. For example, 4/M / means that the macro applies only at the main section prompt. For example, the macro SP.MCR 4/M / {EN J SEMIPRV will substitute "J SEMIPRV" for "SP" when at the main prompt, but NOT for "SP" inside the message read command ("R SP L"). PLANNING YOUR USER INTERFACE 7-13 Note: a macro will be ignored if its name is the same as a command symbol. To use 1, 2, 3, etc. for macro commands, you must disable or substitute other symbols for the SysOp commands. The first line of a macro must be the minimum security level to use the macro. The macro will simply be ignored if the caller has insufficient security. The second line will be parsed and replace the macro name. The remaining lines will be read from disk and processed as required. Macro commands have the same structure as SmartText variables: <command prefix><command name> where <command prefix> is the SmartText command specified in CONFIG. The symbol "{" (ASCII 123) is the default. The <command name> consists of two characters. Lines that are not valid macro commands are simply passed to RBBS-PC as if the user had typed them in. There are three differences between SmartText variables and macro commands: (1) Macro commands must be the first three characters on a line, whereas SmartText variables can occur anywhere on a line. (2) Macro commands can have an argument after the command name, and( (3) A macro command can apply to a block of lines following it. 7.8.2 Macro Commands -------------------- RBBS-PC "Macro" Commands include the capability of having commands executed within the "macro" rather than simply passing keystrokes to RBBS-PC. In all prompts and blocks, substitution is supported for both stored answers SmartText variables. The following is a list and description of valid "macro" commands: *0 - display what follows on the line with no carriage return. *1 - display what follows on the line with a carriage return. *B - display what follows on subsequent lines. *F - display the named file that follows. nn - display a prompt and store result in work variable nn. WT - pause for the number of seconds specified after "WT". >> - append the following block of text to the file specified. ST - Stack the characters immediately following the "ST". M! - Execute the named macro that follows on the same line. ON - Case logic for branching within macros based on stored results. EY - Echo the text passed in macros as keystrokes. EN - Do not echo the macro keystrokes. << - Display fields from a file in a form. := - Assign value to a work variable LV - Verify that answer of one in a list NV - Verify that answer is between two integers CV - Verify that answer is between two character values LO - Set location for Fast File Searches for download, upload, view The syntax and an example of each command follows: *0 - display what follows on the line with no carriage return. {*0Press any key to continue RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-14 *1 - display what follows on the line with a carriage return. {*1{FN, I hope you enjoyed your tour of the board! The caller's first name is substituted for the SmartText variable "{FN." *B - display what follows on subsequent lines, each line with a carriage return, up to the line beginning with "{END". {*B This is an example of a macro's ability to display multiple lines. The macro command is {*B and it will display all lines until it encounters one beginning with {END. Like it, {FN? {END The caller will seen everything between the first and last lines, with the first name substituted into the last line displayed. *F - display the named file that follows. {*F L:\RBBS\HELP.LST will display the file HELP.LST. nn - use the text that follows on the line as a prompt and store the answer in an internal working variable numbered nn. nn must be two digits and can be 01, 02, 03, ..., 99. CONFIG parameter 94 controls the maximum # of work variables. {01Please enter the Department you work for: {02Please enter your Office number: This will store the answers in work variable # 1 and 2, which can be subsequently referenced as "[1]" and "[2]". You can have as many work variables as specified in CONFIG parameter 94. Variables that are reused have their values overwritten. WT - pause for the number of seconds specified after "WT". {WT 2 will wait for 2 seconds. >> - append the following block of text to the file specified on this line. {>> C:MACRO.DAT "{FN","{LN","[1]","[2]" {END will append the following line to the file named MACRO.DAT on drive C:, assuming the caller is KEN GOOSENS, and he responded to the above prompts for Department with "Controller" and Office # with "107". Then the line what would be written out is: "KEN","GOOSENS","Controller","107" PLANNING YOUR USER INTERFACE 7-15 As many lines can be included as desired. Simply end the block to be written out with "{END" as the beginning of the line. Some data base managers want fixed length files and this is possible in the macro append. Just add "/FL" on the macro command line. Rather than replace, the substitution will overlay the line at the "[", thus keeping the output fixed length. Lets suppose that the first work variable has "A" as a value, the second work variable has the value "123456", the third work variable has "Henry" as a value, and the caller's first name is KEN. Then {>> C:\RBBS\DAT.FIL /FL [1][2]....[3]...............{FN........ {END would add the following line into DAT.FIL A 123456.Henry.............KEN......... Normally, blanks would be put where dots are show. ST - Stack the characters immediately following the "ST". {ST will stack a carriage return (no characters). And {STD [1] [2] would stack "D RBBS-EXE.ARC Z" - as if they were typed and ENTER pressed - if the first work variable had "RBBS-PC.EXE" and the second work variable held "Z". It is important to note that "macros" are so transparent to RBBS-PC that if you use macros to display text at an RBBS-PC prompt like "Enter command? ", RBBS-PC will continue to sit there waiting for an answer. A stacked carriage return at the end will cause the prompt to be redisplayed, though the effect of the stack will vary with the particular prompt. M! - Execute the named macro that follows on the same line. E.g. {M! ORDER will execute the macro called ORDER. RBBS-PC does NOT return to the invoking macro when the named macro is complete. Also, The full file name of the macro to execute is not here used (i.e. ORDER.MCR), only the file prefix -- ORDER. As is shown in the example of the ON command, the macro name can have a drive/path and/or extension. If only a prefix is put in, RBBS-PC will automatically add the drive/path and extension for macros specified in CONFIG parameter 79 and parameter 80. Putting in a drive/path/extension that is different from CONFIG's assures that no caller can invoke the macro -- it only can be used internally by your application. ON - Case logic for macros. This allows responses to be tested against and branching logic developed within a "macro". An example would be: {ON 1 RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-16 {==A {M! D:\HIDDEN\CHOICEA.MCR {==B {*1You have selected option B {02Why did you select B? {==C {M! D:\HIDDEN\CHOICEA.MCR {END ON EY - Echo the text passed in macros as if keystrokes. The default is to echo. EN - Do not echo the macro keystrokes. An example would be: {EN {*1 The following commands will be executed but now shown {01 Press Enter when ready R L A {EY {*1 now you will see the responses to the prompts {01 Press Enter when ready R L A << - Display fields from a file in a form. This is one of the most powerful macro commands. It allows data to be stored in compact, data format but retrieved into a form for display to a caller. There are 5 parameters that can follow the macro command: <file name> <file format> <data#> <submode> <rec-pause> where: "<file name>" is the name of the data file that has records to read, "<file format>" is "/V" if data is stored in variable length format and "/F" if fixed length format, "<data#>" is the number of separate fields in a record for variable length data and the length of the data if fixed length, "<submode>" is the mode used to substitute data in the following form "/FL" if the form is fixed length, meaning that data is overlaid into the form so as not to change any lengths. "<rec-pause>" should be "/1" if you want to pause after each record rather than when the screen fills. An example of a "macro" that uses this capability is as follows: {*1 -TOPIC- - DATA # - - VOICE # - -First Name- -Last Name- {<< C:\RBBS\RHLP.DAT /V 5 /FL [1] [2] [3] [5] [4] {END Note that spaces occur after the "[4]". If the file RHLP.DAT contains "DOORS","703-978-6360","0","Ken","Goosens" PLANNING YOUR USER INTERFACE 7-17 "PROTOCOLS","407-627-6969","407-627-9767","Doug","Azzarito" then the caller would see -TOPIC- - DATA # - - VOICE # - -First Name- -Last Name- DOORS 703-978-6360 0 Ken Goosens PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito The same example using fixed length data would be {*1 -TOPIC- - DATA # - - VOICE # - - Name - {<< C:\RBBS\RFLH.DAT /F 69 /FL [1](34:12) [1](46:12) [1](58:12) [1](1:33) {END where RFLH.DAT contains: Ken Goosens DOORS 703-978-63600 Doug Azzarito PROTOCOLS 407-627-6969407-627-9767 This would produce the following for the caller: -TOPIC- - DATA # - - VOICE # - - Name - DOORS 703-978-6360 0 Ken Goosens PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito Note that work fields support sub-field references in the format: [n](x:y) where n is the work field number, "x" is the beginning column, and "y" is the # of bytes to get. If work field two had a value "123abcde" then "[2](3:4)" would have "3abc" as its value. Fixed length records are always referenced as work variable one. := - Assign a value to a work variable. Work variables can be assigned a value inside a macro. The command to do this is ":=". E.g. {:= 5 OK assigns string "OK" to work variable 5. LV, NV, and CV - Macros can edit the responses to questions. Edits can constrain the answer to - one of a list - a numeric value between two values - a character value between two values An editing constraint must be put in front of the actual macro question it applies to, and a constraint applies only to the next question and does not remain operative. The commands for these are respectively "LV" (List Verify), "NV" (Numeric Verify), and "CV" (Character Verify). The list verify uses the first character after the command as a delimiter between valid responses. E.g. "{LV;R;A;E;" means that only "R", "A", and "E" will be accepted as answers ("{LV/R/A/E/" would have the same effect). RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-18 Semi-colon is the best delimiter in general because it cannot be entered as a value. Numeric and Character verify check inclusive ranges. Thus "{NV 7 11" will accept 7, 8, 9, 10, or 11. The numeric value must be an integer between -32,768 and 32,767. To accept answers B through E, the macro edit command is "{CV B E". Whenever an answer fails an edit, the message "Invalid answer <...>" is given with the answer received between brackets, and the question is asked again. An example of a macro with edits is: 4 {*1 Verification macro {*1 now checking list... {LV;A;F;W; {01 Enter A, F, or W {*1 now testing numeric range... {NV 5 15 {01 Enter a number between 5 and 15 {*1 now testing character range... {CV D J {01 Enter a character between D and J LO - Sets location that a file is to be searched for in an upload, download, or view request. Followed by a drive path. Useful when want to have a macro execute in front of a download or upload for a file which is really available (see section 12.9). Applies only to Fast File Search. For example, {LO F:\DF1\ would set the file location to drive F subdirectory DF1. 7.8.3 A Sample Macro -------------------- Suppose A)bandon conference is to be implemented in RBBS-PC. To do this, the command A)nswer questionnaires must be assigned a different letter. Else A will always invoke answer instead. Then the macro file could contain 5 J M The command "A" will then be followed by "Rejoining MAIN". Incidentally, if the macro had been implemented by 5 J M The only difference is that the prompt for what conference to join will be displayed, "M" then would be displayed as if the caller had typed it, and then main would be rejoined. The difference is caused by the fact that the first line after the security level is what replaces the macro name, so in the first case "M" preempts the prompt but not in the second. PLANNING YOUR USER INTERFACE 7-19 7.8.4 On-line Data Base With Macros & Questionnaires ---------------------------------------------------- RBBS-PC provides the SysOp with the ability to offer callers access to an on-line database both internally (using macros and questionnaires) and externally to RBBS-PC (see Appendix R). RBBS-PC's internal Remote Data Base feature gives the SysOp the ability to: - set up unlimited numbers of named data bases - set up menus to interact with the user - prompt users for data - use Metavariables - both work variables and SmartText variables. - store user's answers in work variables. Any subfield in a work variable can be referenced. - display, or store all metavariables - process commands conditionally - save Metavariables to file through templates, allowing data to be stored in virtually any format desired - retrieve data into templates for display. - do full screen data entry RBBS-PC's support for "full screen" questionnaires and macros takes some work on the SysOp's part. The SysOp must use ANSI screen commands. The SysOp must then arrange to transmit the "template" that clears the callers screen and writes the appropriate static text (lines, labels, etc.) on the callers screen. Then the data the user is to see is transmitted onto the caller's screen. The "full screen" support does not allow the caller to use keys like tab and cursor arrows to move around on the screen. It is "full screen" in the sense that the caller sees all the data that is to be entered and the cursor moves from field to field. On-line Database Example ------------------------ This application manages a data base of callers who are willing to help with RBBS-PC by topic. It is controlled at a high level by the following questionnaire. C:DUMMY.DAT,4 * This questionnaire is for finding help with RBBS-PC by topic. * Please register yourself if you * - are willing to help others, and * - know enough about a topic to help * * Examples of topics people need help with: * Desqview Modem models (HST, Everex, USR Internal, etc.) * PC-Slaves Protocols Conferences FMS * Doors DoubleDos Sub-boards PUI * Questionnaires 10-Net Macros Uploads * MU-Purge File maint. Personal dnld Caller Analysis * :-[prompt]- T ? V)iew database, E)nter new data, Q)uit (V,A,Q) =V-[view]-=E-[add]-=Q-[quit]-= -[prompt]- :-[view]- M C:\RBBS\VIEWHELP.MCR >-[prompt]- :-[quit]- @ RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-20 :-[add]- * 703-978-6360 ?1 BBS data number * 703-978-4339 ?2 Voice # (evening, 0 not to give) * You can specify as many topics as desired, one at a time. * :-[topic]- ?3 RBBS-PC topic you will help others with, or Q)uit =Q-[prompt]-= -[addrec]- :-[addrec]- * -Topic- - Data # - - Voice # - Last Name First Name */FL[3] [1] [2] {LN {FN T ?Really add this record (Y,N) =Y-[really]-=N-[topic]-= -[addrec]- :-[really]- M C:\RBBS\ADDHELP.MCR >-[topic]- Two macros are used by this questionnaire: VIEWHELP.MCR for displaying the data base, and ADDHELP.MCR for appending new data to the data base. VIEWHELP.MCR contains 5 {*1 -Topic- - Data # - - Voice # - Last Name First Name {*F RBBSHELP.DAT ADDHELP.MCR contains 5 {>> RBBSHELP.DAT /FL [3] [1] [2] {LN {FN {END Full Screen Example Full screen is available only in a color graphics version of questionnaires and macros. A long application for collecting BBS information is given in these following files: REGRBBS.DEF - Questionnaire driver, TTY version REGRBBSC.DEF - Color graphics version of questionnaire driver VUNRBBS.MCR - View data base macro, TTY version VUNRBBSC.MCR - View data base macro, Color graphics version SVRBBS.MCR - Macro to save data to a comma separated data file These files can generally be download from most bulletin board systems. However, they are definitely available on Ken Goosens' RBBS-PC system at (703) 978-6360. Hints for Building Remote Data Base Applications ------------------------------------------------ Generally you will have: PLANNING YOUR USER INTERFACE 7-21 - a questionnaire driver that gives caller option to exit, view database, or Enter new data - a macro to retrieve data from file to a form - a macro to save data in a data base format - a data entry routine in the questionnaire. Creating a "full-screen" application is more complicated that than a line- at-a-time (i.e. TTY) application. For full-screen applications, you will want to: - paint a template with everything but the data values, such as row and column labels and titles. - clear out the existing values in a form and then put in the new values. Only the changes to the screen are transmitted rather than retransmitting the entire screen when only a part changes. ANSI commands are used to control the screen. Where [ESC] stands for the one-character Escape (ASCII 27), the most useful ANSI commands to know are: [ESC][2J - clear the screen. [ESC][K - clear from current cursor position to end of line. Cursor position after clearing is same as before. [ESC][X;Yf - position the cursor on row x and column Y. E.g. "[ESC][5;10f" positions on column 10 of row 5. Case is significant in ANSI commands, so beware that "[ESC][k" will NOT clear to end of line, and "[ESC][1;7F" will not position the cursor. You can use ANSI commands to set color and blink characters. An easy way consistent with RBBS-PC is to set colors using the SmartText variables C0, C1, ..., C4, where 1-4 are the colors set in CONFIG parameter 323, parameter 324, parameter 325, and parameter 326. C0 is "emphasis off," and restores normal text color preference of the caller. An example that clears the screen, sets color to 1, positions on line 1, column 15, prints "-Sample Title-", sets color to caller's text preference, prints 2 spaces, and then prints value of work variable 1 is as follows: [ESC][2J{C1[ESC]1;15f-Sample Title-{C0 [1]